---
title: Guide to creating Components
description: "How to contribute high-quality, intuitive components to chakra"
tags: ["component", "guide", "process"]
author: segunadebayo
---

The goal of this document is to outline the process we follow internally to
develop any Chakra components. At Chakra UI, we strive to make the entire
codebase high-quality, readable, and easy to contribute.

**At the top level, we have a 5 step process to building components:**

1. Share and discuss the component
2. Setup the component package
3. Write the `README` for the component
4. Build the component and write tests as you go
5. Document the component

## 1. Share your ideas

We believe collaboration and communication encourages a mix of expertise, ideas
and perspectives to come together to achieve the level of quality we need for
Chakra UI.

There are two recommended ways to share your component ideas:

- Visit our Discord Server and post it in the `#💡-api-discussion` Channel to
  get a conversation rolling.
- Open a Github Discussion and share your component ideas to get community-wide
  feedback and inputs.

To help us to give quality feedback, we recommended that you follow this
structure for any component or hook you want to contribute:

- Quick description of the idea
- What Problem does it solve?
- What existing solutions have you tried?
- Your solution and how it's better than the alternatives
- API examples

## 2. Setup the component package

Assuming your component idea was accepted by the core team, and you need to
start building, here's what you need to do:

- Run the `yarn gen:pkg` command to bootstrap a package and symlink with lerna.
- Update the `package.json` with more relevant content. You need to update
  `description`, `keywords`, `peerDependencies`, `dependencies`, etc.
- Test the build, lint, and test scripts are working correctly

Voila! You're ready to write some beautiful code!

## 3. Build the component or hook

Whether you're developing a component or hook, we have a set of best practices
we advice to follow to deliver on the quality expectations.

### General

- Ensure you check the `@chakra-ui/hooks` and `@chakra-ui/utils` package to be
  sure we don't already have the hook you're looking to create.
- Leverage existing code, hook, or utils as much as possible.
- Separate component logic from UI by writing hooks, and then writing the
  component theme or styles

### Hooks

Add types for custom hook props and return type

```tsx
export interface UseHookProps {}

export function useHook(props: UseHookProps) {
  return {}
}

export type UseHookReturn = ReturnType<typeof useHook>
```

### TypeScript

The end goal of this ensure all Chakra UI components are as strongly typed as
possible to enable teams leverage the library.

- Prefer named exports instead export default
- Reduce use of Generics. Generic code can be highly reusable, but that can also
  come with high complexity and mental overhead.
- Add prop types and return type for hooks
- Add JSDoc comments for each type (used for prop table generation)

## 4. Build and Test

The initial component setup include `test` and `build` scripts you can use to
bundle the component for NPM.

Ensure you run these commands before creating a PR.

### Testing Checklist

- [ ] Common use cases snapshotted
- [ ] Common use cases run through `axe`/`toHaveNoViolations`
- [ ] `role`/`aria`/`data` attributes tested
- [ ] Component behaviors tested (reacts to events, handles callbacks
      appropriately, updates state correctly, etc.)
- [ ] Controlled/uncontrolled use cases tested
- [ ] Associated utils/helpers/etc. tested

## 5. Documentation

- Add `README.md` component to the package
- Add the component to the website in the `docs-sidebar` and directory.

## Resources

### TypeScript

- Clean Code Guide: https://github.com/labs42io/clean-code-typescript

- Best TypeScript
  Practices:https://github.com/typescript-cheatsheets/react-typescript-cheatsheet

### Testing

- Common React testing library scenarios:
  https://react-testing-library-examples.netlify.com/

- Common Testing Practices:
  https://github.com/mawrkus/js-unit-testing-guide#unit-tests
